Sometimes you may want to simply override a template (see Template Loading) or create an alternative template in an existing theme. However, other times you might want to create your own entire theme, especially if you are planning to build a rich set of unique and reusable templates for your organization.

There are three ways to create new themes:

  • Create a new theme from scratch (hard!)
  • Extend an existing theme
  • Wrap an existing theme

We don't ever recommend creating a new theme from scratch. Rather, we believe that the simple theme provides enough of the basics for you to either extend or wrap, thereby creating your own unique theme. No matter which method your choose (often you end up using a bit of both methods, as they aren't mutually exclusive), we strongly you unpack the WebWork jar and look at the source templates for all the provided themes. This will give you a good understanding of how to make your own templates and themes.

Wrapping an Existing Theme

Taking a look at the xhtml theme, we can see that the templates there make extensive use of a wrapping technique. For example, a template might look like:

<#include "/${parameters.templateDir}/xhtml/controlheader.ftl" />
<#include "/${parameters.templateDir}/simple/xxx.ftl" />
<#include "/${parameters.templateDir}/xhtml/controlfooter.ftl" />

This template is simply wrapping the simple theme's existing template with a header and a footer. This is a great way to add additional behavior around the basic HTML elements provided by the simple theme.

Extending an Existing Theme

The theme infrastructure provided by WebWork also allows themes to extend an existing theme. What this means is that a theme may contain a theme.properties with a parent entry that contains the name of the theme that you would like to extend. For example, the ajax theme extends the xhtml theme in this way.

By extending a theme, you are not required to implement every single template that the Tags use. Rather, you only need to implement templates that you wish to override. All other templates will be loaded from the parent template.